Cloudinary MO の Mapping Function を使ってカスタムパラメータで画像を変換してみた

Cloudinary の新しい Media Optimizer の機能「Mapping Function」について解説します。

#Cloudinary

#画像処理

#CDN

Ito ma

2021.07.24

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

先日、Cloudinaryの新しいサービスである Media Optimizer (MO) に関する記事をご紹介しました。

Cloudinary MO でもっと手軽に画像最適化を導入できるように！

そちらでは省いた、MOの高度な機能 Mapping Function について、今回の記事でご紹介します。

Mapping Function とは

Cloudinaryには画像や動画を最適化させるための変換パラメータがあります。

ざっくり言うと、Mapping Functionによって、URL内で追加の変換パラメータを指定して動的に適用させたり、URLに独自のカスタムパラメータを指定してそれに応じた変換を適用させたりすることが可能となります。

この、「指定されたURL内のパラメータに対してどのように変換を適用させるか」というマッピングを Mapping Function で定義します。

Mapping Function は、Delivery Profiles の設定内で指定する項目の一つです。

おさらいとなりますが、MOにおける配信URLは、下記のように構成されており、この Path Prefix ごとにオリジンソースと変換セットの組み合わせを定義します。

https://[MOのクラウド名].mo.cloudinary.net/[Path Prefix]/[アセットのパス]

冒頭の記事内でも記載しているように、あるパスに対してある変換を適用する、という通常の変換適用を利用するだけであれば、Mapping Functionは関係ありません。なので、デフォルトで選択されている「Media Optimizer」のままでOKです。

一方、URLの追加パラメータで特定の変換を適用させる場合にMapping Functionを正しく設定する必要があります。

例えば、以下のような設定の場合に、URL内で追加パラメータを指定して、最終的にf_auto,q_auto,w_300を適用させることができます。

Path Prefix: cm
- ベース変換: f_auto,q_auto
アセットのパス: ito-test/Reichstag.jpg

# 例1
https://[ドメイン]/cm/ito-test/Reichstag.jpg?tx=w_300
# 例2
https://[ドメイン]/cm/w_300/ito-test/Reichstag.jpg
# 例3
https://[ドメイン]/cm/ito-test/Reichstag.jpg?width=300

上記例のように異なる形式で指定するためには、それぞれに適切なMapping Functionを設定するのです。

3つのパターン

大きく分けて3つ、デフォルトで作成されている2つと、それ以外に自分で作成する方法があります。（デフォルトの2つは削除することはできません。）

Media Optimizer：末尾の?tx=に続けて変換パラメータを指定（例1）
Programmable Media：通常のCloudinaryのURLと同様に変換パラメータを指定（例2）
カスタム：末尾の?に続くクエリをJavascriptコードで自由に定義（例3）

最終的に適用できるのはMOでサポートされる変換のみで、MOにおいてはウォーターマークやエフェクトの多くは使用することができませんのでご注意ください。

Media Optimizer

Mapping Function のデフォルト値です。

このオプションを選択した場合、先ほどの「例1」のように、URLの末尾で?tx=に続けてCloudinaryの変換パラメータを指定することで、ベース変換に加えて追加の変換を適用させることができます。

追加パラメータなし（ベース: f_auto,q_auto）
- ~/cm/trip/hb1.jpg
追加で400x400のサイズとする場合
- ~/cm/trip/hb1.jpg?tx=c_fill,w_400,h_400

Programmable Media

オリジンソースが Cloudinary の場合、「Media Optimizer」も利用可能ですが、機能を最大限活用できるようこのオプションを選択することが推奨されています。

この場合、MOのドメインと「Path Prefix」に続くURL形式が通常のCloudinaryの配信URLと似ており、[リソースタイプ]/[タイプ]/[追加の変換パラメータ]/[パブリックID] を指定することで、ベース変換に加えて追加の変換を適用させることができます。

リソースタイプとタイプは画像であればimage/uploadで、これはデフォルト値のため、先ほどの「例2」のように省略することも可能です。

追加パラメータなし（ベース: f_auto,q_auto）
- ~/cm/ito-test/bike.jpg
追加で横幅を200pxにスケールする場合
- ~/cm/image/upload/c_scale,w_200/ito-test/bike.jpg
image/uploadを省略した場合
- ~/cm/c_scale,w_200/ito-test/bike.jpg
通常のCloudinaryのURL
- https://res.cloudinary.com/[CLOUD-NAME]/image/upload/c_scale,f_auto,q_auto,w_200/ito-test/bike.jpg

リソースタイプには、動画の場合はvideo、それ以外はrawを指定します。

動画の場合（追加で横幅を200pxにスケール）
- ~/cm/video/upload/c_scale,w_200/ito-test/video.mp4
CSVファイルの場合
- ~/cm/raw/upload/ito-test/sample.csv

その他にもこちらの記事で紹介しているような動的SEOサフィックスの機能を使用することも可能です。

なお、Cloudinary 以外のオリジンソースの場合には、このオプションを選択するとエラーとなるので注意しましょう。

逆にこのオプションを選択している限り、Media Optimizerのように~/image.jpg?tx=w_300などと指定しても、?以降のクエリは無視されて変換は適用されません。

カスタム

新しい Mapping Function を作成し、JavascriptのコードでURL末尾の?以降のクエリをどのように処理するか定義することができます。

例えば、次のようなことが可能となります。

size=smallと指定した場合、追加で150x100にフィットするよう変換させる
- ~/cm/trip/hb2.jpg?size=small
Cloudinaryのものではない形式のパラメータを指定しても変換できるようにする
- ~/cm/trip/hb2.jpg?filter=w407
trn=noneと指定した場合、ベース変換を適用させない
- ~/cm/trip/hb2.jpg?trn=none

今回は試しにドキュメントのコード例に載っている Example 1 を元にやってみました。

MOのコンソールの Configuration > Media Sources > Add new より新しい Mapping Function を作成します。名前を付与し、コードを入力します。

コード

function map(request, environment) {
  let transformation = environment.defaultTransformation + '/';

  // width と height のクエリがあれば変換に追加する
  if (request.query.width && request.query.height) {
    transformation += `c_limit,h_${request.query.height},w_${request.query.width}/`;
  } 
  // size のクエリがあればそれぞれ特定の変換を追加する
  else if (request.query.size) {
    switch(request.query.size) {
      case 'small':
        transformation += "c_fit,h_100,w_150/";
        break;
      case 'medium':
        transformation += "c_fit,h_240,w_360/";
        break;
      case 'large':
        transformation += "c_fit,h_480,w_720/";
        break;
    }
  }
  let path = request.path;

  // fwd_key 用に Path Prefix を除去する
  if (environment.pathPrefix.length > 0) {
      path = path.slice(`/${environment.pathPrefix}/`.length);
  }

  return {
    fwd_key: path,
    media_key: request.path,
    transformation,
    resource_type: 'image',
  };
}

パラメータ

ここで使用されているパラメータは次の通りです。

パラメータ	内容	例
request.url	リクエストURL	https://[MO-CLOUD-NAME].mo.cloudinary.net/cm/trip/hb2.jpg?width=300&height=200
request.path	ドメイン以降クエリ以前のパス	/cm/trip/hb2.jpg
request.query	JSON形式にデコードされたクエリ	{ width: '300', height: '200' }
environment.defaultTransformation	ベース変換(変換の名前にt_を付与したもの)	t_auto_format_auto_quality
environment.pathPrefix	Delivery Profileで定義しているPath Prefix	cm

レスポンス

期待されるレスポンスは次の通りです。

レスポンス	内容	例
fwd_key	オリジンソースのパス（Media Source内のURI Templateで指定しているプレフィックスは除く）	trip/hb2.jpg
media_key	MOにおけるパス	/cm/trip/hb2.jpg
transformation	適用させる変換パラメータ	t_auto_format_auto_quality/c_limit,h_200,w_300/
resource_type	リソースタイプ	image, video, または raw